1994-1996 by Oberon microsystems, Inc., Switzerland.
All rights reserved. No part of this publication may be reproduced in any form or by any means, without prior written permission by Oberon microsystems. The only exception is the free electronic distribution of the education version of Oberon/F (see the accompanying
copyright
notice
for details).
Oberon/F module interfaces and their descriptions in particular may not be used in other works without written permission.
Oberon microsystems, Inc.
Technoparkstrasse 1
CH-8005 Z
Switzerland
Oberon is a trademark of ETH Z
rich, Switzerland.
Oberon/F, Oberon/L, "Oberon by Example", "The Oberon Tribune", "Oberon Developer Forum", and "Drag & Pick" are trademarks of Oberon microsystems, Inc.
All other trademarks and registered trademarks belong to their respective owners.
Helvetica
StdLinks.ShowTarget('Introduction')
Helvetica
StdLinks.ShowTarget('Texts')
StdLinks.ShowTarget('Forms')
StdLinks.ShowTarget('Commands')
StdLinks.ShowTarget('Files')
Helvetica
StdLinks.TargetDesc
Introduction
Helvetica
Texts
Helvetica
HostPictures.StdViewDesc
Geneva
position 3
position 0
Helvetica
Forms
Helvetica
Controls.PushButtonDesc
Controls.ControlDesc
Dialog.Beep
StdCmds.OpenDoc('Obx/Docu/Buttons')
Geneva
DevCommanders.StdViewDesc
DevCommanders.ViewDesc
FormViews.StdViewDesc
FormViews.ViewDesc
FormModels.StdModelDesc
FormModels.ModelDesc
Controls.CaptionDesc
ObxForms4.para.limit
limit
Controls.FieldDesc
Controls.ControlDesc
Views.ViewDesc
Stores.StoreDesc
ObxForms3.para.limit
ObxForms3.NotifyLimit
ObxForms3.para.sum
ObxForms3.para.sum
ObxForms3.ReadOnlyGuard
FormControllers.StdControllerDesc
FormControllers.ControllerDesc
Containers.ControllerDesc
Controllers.ControllerDesc
TextModels.AttributesDesc
Chicago
Chicago
Chicago
ObxForms3.para.limit
ObxForms3.NotifyLimit
ObxForms3.para.sum
ObxForms3.ReadOnlyGuard
ObxForms2.NotifyLimit
TextRulers.StdRulerDesc
TextRulers.RulerDesc
TextRulers.StdStyleDesc
TextRulers.StyleDesc
Models.ModelDesc
Stores.ElemDesc
TextRulers.AttributesDesc
StdLinks.TargetDesc
Commands
Helvetica
Helvetica
Helvetica
Files
HostPictures.StdViewDesc
Geneva
riders
at beginning
at pos = 5
at end
Oberon/F
Command Tutorial
Copyright Notice
Contents
Introduction
Working
Texts
Working
Forms
Working
Commands
Working
Files
Introduction
In Oberon/F, two major levels of programming can be distinguished.
The simplest level is the programming of commands. A command is a procedure that performs one or several operations like opening a window, pasting a text, stretching or selecting parts of a graph. Commands are usually invoked interactively by the user, e.g. by selecting a menu entry or by clicking on a button, and they typically operate on abstract data types, e.g. on texts or on forms.
Command programming is sometimes called scripting, or component integration.
The second level of programming is the programming of views. A view provides a visual presentation of data, e.g. in a window or as part of another view. Views can be stored and printed, and their contents can be edited interactively, e.g. through cut, copy, drag and drop, etc.
View programming is sometimes called component creation.
In this tutorial, there is one chapter on command programming, and another chapter on view programming.
This tutorial introduces the most fundamental aspects of Oberon/F by means of graduated examples. It doesn't attempt to show all features supported by Oberon/F. Your copy of the software contains additional documentation on-line, e.g. commented sources of views or examples highlighting more specialized aspects of the framework. For a complete and systematic presentation of the Oberon/F interfaces, the reader is referred to the reference part of the on-line documentation.
This chapter presents several simple example programs, which demonstrate how the standard text and form abstractions can be used from within a program.
Working with Texts
When using a new programming environment, many programmers first write a program which puts the string "Hello World" onto the screen. In this tutorial, you'll find several such "Hello World" programs with different degrees of sophistication.
Our first "Hello World" program writes the string "Hello World" into the log window. This window is usually open when Oberon/F is used as programming environment. Whether or not the log window is opened on startup of Oberon/F depends on the configuration, which the user can change to his liking, as described in the Oberon/F User's Guide.
MODULE ObxText0;
IMPORT Out;
PROCEDURE Do*;
BEGIN
Out.String("Hello World"); Out.Ln
END Do;
END ObxText0.
In this first example program, we can see several properties of an Oberon program:
An Oberon program consists of one or more modules, e.g. ObxText0.
One module may use ("import") other modules, e.g. ObxText0 imports Out.
Standard modules of Oberon can be imported by new modules, e.g. ObxText0 imports the library module Out.
Procedures of another module are referenced as "module.procedure", e.g. Out.String or Out.Ln.
Procedures which are accessible to other modules must be marked as "exported" (the "*" mark of ObxText0.Do).
The behavior of a program is provided to the system simply as one or several exported procedures, e.g. ObxText0.Do.
In order to toy around with the above example program, you can open a text window (actually a window containing a document containing a text view) by choosing New in the File menu. After you have typed in the above source text, you can compile the module by choosing Compile in the Dev menu. In the log window you can see whether compilation was successful.
If no error message has appeared in the log, you can execute procedure ObxText0.Do by selecting the string "ObxText0.Do" (just type it in after the module's text, in the same window) and then choosing Execute in the Dev menu. As a result, "Hello World" is written to the log. You can repeat Execute as often as you like.
In Oberon, an exported procedure like ObxText0.Do is called a command, if it should be called from the user interface, rather than from other modules (although this is also possible). Commands can be activated in various ways. In production software, commands are typically activated by selecting a menu entry or by clicking on a button.
Since module Out is a useful tool, we want to give an overview over its facilities, so we can use it in later example programs. An overview over a module's facilities is called the module's definition. Usually, a module definition in Oberon is written like the module itself, but with all non-exported items left out, with the procedure bodies eliminated, without the export marks, and with the pseudo-keyword DEFINITION instead of MODULE. Note however, that this is merely a convention for documentation purposes, and that the compiler cannot use a definition as input. The Browser automatically generates a definition text out of a compiled module's symbol file (-> DevBrowser).
Here is the definition of module ObxText0:
DEFINITION ObxText0;
PROCEDURE Do;
END ObxText0.
The definition of module Out is given below.
DEFINITION Out;
PROCEDURE Open;
PROCEDURE Char (ch: CHAR);
PROCEDURE Ln;
PROCEDURE Int (i, n: LONGINT);
PROCEDURE Real (x: REAL; n: INTEGER);
PROCEDURE String (str: ARRAY OF CHAR);
END Out.
Open opens a log window, if there isn't one open already. In our examples here, we assume the log to be open, and thus never call this procedure. The other procedures write characters, carriage returns, integers, reals, and strings into the log. The parameter n in the procedures Int and Real denotes the number of digits to be used in the number's representation. If it is smaller than necessary (e.g. zero), the minimal number of digits is used.
Another example of the use of module Out is the following program, whose ObxText1.Sum command calculates the sum 0 + 1 + 2 + 3 + 4 + 5 + 6 + 7:
MODULE ObxText1;
IMPORT Out;
PROCEDURE Sum*;
VAR i, sum: INTEGER;
BEGIN
i := 1; sum := 0;
WHILE i <= 7 DO
sum := sum + i;
i := i + 1
END;
Out.String("the sum of 0..7 yields "); Out.Int(sum, 0); Out.Ln
END Sum;
END ObxText1.
Alas, this program and the first "Hello World" mix their outputs in one and the same window, the log. Thus we'll present another "Hello World" program which explicitly generates a text, inserts this text in a text view, and opens this text view in its own window; independent of the log window. For the time being, a "view" may simply be regarded as the contents of a window.
A text is an abstract data type, i.e. a data type which hides its internal workings in the module in which it is defined (i.e. in module TextModels). A text contains a sequence of characters, plus character attributes like font or color. A text does not know how to display itself, this capability is embodied in a text view. A text view is also an abstract data type, defined in module TextViews.
Our next program imports TextModels and TextViews, plus modules Views. Furthermore, module TextMappers is imported, which provides services to generate or to scan formatted text:
MODULE ObxText2;
IMPORT Views, TextModels, TextMappers, TextViews;
PROCEDURE Do*;
VAR t: TextModels.Model; f: TextMappers.Formatter; v: TextViews.View;
BEGIN
t := TextModels.dir.New(); (* produce an empty text *)
f.ConnectTo(t); (* open formatter on text *)
f.WriteString("Hello World"); f.WriteLn; (* write string and line separator *)
v := TextViews.dir.New(t); (* produce a view which displays text t *)
Views.OpenView(v) (* open the view in a window *)
END Do;
END ObxText2.
For this example, we can make the following remarks:
Texts and text views are produced by so-called directory objects, namely TextModels.dir and TextViews.dir.
Directory objects are exported global variables which contain New functions.
Directory objects allocate and initialize variables of abstract data types.
TextMappers provides a data type called a Formatter, which can write formatted output into a text object.
The text formatter provides formatting procedures like WriteString or WriteLn.
The text formatter is connected to the text t.
The view is opened in a window, whose contents can be edited, stored, or printed; just like any other window that contains a text.
Generating text output is often useful, but seldom sufficient. Usually we need a way to pass one or several input values to a program, and often a text is a suitable input type (e.g. for the compiler).
In Oberon/F, visible text is represented in a text data structure, and this data structure can be accessed, and used as input, by any command. This makes it possible to use text produced by one command as input for another command.
For example, the Loaded
Modules command in the Info menu generates a list of all loaded modules. This list is simply a text; it can be edited, stored, and printed just like any text typed in by the user.
The menu item Interface in the same menu takes a text, and looks for a text selection. If it finds a selection, it reads the text in the selection (input!) and interprets it as the name of a module. If it finds a module with this name, it opens a window with the definition of this module. This interface browser is an example of how a command uses a text generated earlier as input, in order to produce a new text as output.
We now want to take a closer look at how a command like Interface gets access to the text produced by Loaded
Modules. The following program shows what happens in essence:
MODULE ObxText3;
IMPORT TextControllers, Out;
PROCEDURE Do*;
VAR c: TextControllers.Controller; beg, end: LONGINT;
BEGIN
c := TextControllers.Focus(); (* get the focus controller, if any *)
IF (c # NIL) & c.HasSelection() THEN (* a text view with a selection must be focus*)
c.GetSelection(beg, end);
Out.String("beg = "); Out.Int(beg, 0); Out.Ln;
Out.String("end = "); Out.Int(end, 0); Out.Ln
ELSE
Out.String("no text focus or no selection"); Out.Ln
END
END Do;
END ObxText3.
Whenever a command needs the contents of a window as input, it must be able to get at the appropriate window, and from there to its contents. At any time, Oberon/F provides access to one window's contents, this window is called the focus window. In user interfaces which support overlapping windows, the focus window is usually the front window.
Sometimes, the role of focus window is actually split between two windows: the front window and a target window. In this case, the target window is a document (e.g. a text document), and the front window a dialog. In the normal case however, the front window also acts as target window.
Menu commands operate on the front window, while commands invoked through buttons in the front window operate on the target window.
Picture a: Window which is both Front and Target Window
Picture b :Target Window is still the same, but a Dialog has become Front Window
A command implementation can get its appropriate focus by calling a suitable function, e.g. TextControllers.Focus as in the above example. This shows that there is another important module in the text subsystem: TextControllers. A text controller handles the interaction of the user with a text displayed in a text view.
After having checked that the focus controller is not NIL and that there currently is a selection, ObxText3 writes the beginning and end positions of the selected text to the log. A text position denotes the left edge of a character, starting at position 0:
Picture c Character Positions
Now we want to write the contents of the selection to the log:
MODULE ObxText4;
IMPORT TextModels, TextControllers, Out;
PROCEDURE Do*;
VAR c: TextControllers.Controller; beg, end: LONGINT;
r: TextModels.Reader; ch: CHAR;
BEGIN
c := TextControllers.Focus(); (* get the focus controller, if any *)
IF (c # NIL) & c.HasSelection() THEN (* a text view with a selection must be focus*)
c.GetSelection(beg, end);
r := c.text.NewReader(NIL); (* create a reader for the view's text *)
r.SetPos(beg); (* position reader at beginning of selection *)
r.ReadChar(ch); (* read first character of selection *)
WHILE (r.Pos() <= end) & ~r.eot DO (* stop at end of selection and at end of text *)
Out.Char(ch);
r.ReadChar(ch) (* read next character in selection *)
END;
Out.Ln
ELSE
Out.String("no text focus or no selection"); Out.Ln
END
END Do;
END ObxText4.
This program is the same as ObxText3, except for the parts in bold face, which are either new or changed.
This example shows the use of a TextModels.Reader. A text reader is an object which implements an access path to a text. The text itself creates its readers. A reader has a position on its text, and provides procedures for positioning on the text (SetPos), for inquiring the reader's current position (Pos) and for reading characters (ReadChar). After every character read, the reader's position is incremented by one.
Working with Forms
Compound User Interface
Forms are essential business tools. The graphical elements that appear in a form layout are sometimes called controls. Typically, most of the graphical elements are text fields, complemented by a variety of buttons.
In contrast to most other development systems on the market today, Oberon/F treats dialogs and controls the same way as it does normal document components, they are just views that form part of a compound document. Consequently, dialogs are stored in the same file format as are all other Oberon/F documents. The result of such a unification of compound documents and user interface controls is sometimes called a compound user interface.
As dialogs and controls both are regular views, they can be contained in any Oberon/F container. Dialogs and controls can for example appear in any text, as the following command button shows:
Forms are special containers which may contain any view at any place. In Picture d an example of a form is shown. It contains text, a logo and several controls.
Controls
Oberon/F comes with a set of standard controls. The following list describes all standard Oberon/F controls. Picture d shows a form containing some of them.
- Command Button A command button is used to execute an Oberon/F command or command sequence. Alternatively, it can be linked to a global variable of type PROCEDURE.
- Field A field displays the value of a global variable which may be a string, an integer or a floating-point number. The value of the variable can be changed through the field. A field can also be linked to a variable of type Dialog.Currency or to an extension of Dialog.Combo.
- Check Box A check box displays the value of a global Boolean variable. This value can be changed with the check box.
- Radio Button A radio button is active at a particular value of a global integer variable.
- List Box A list box allows to select one value out of a list of choices. It is linked to a variable whose type is an extension of Dialog.Enumeration.
- Selection Box A selection box allows to select a subset out of a set of choices. It is linked to a variable whose type is an extension of Dialog.Selection or Dialog.LargeSet.
- Combo Box A combo box is a text field whose contents can also be set over a pop-up menu. It is linked to a variable whose type is an extension of Dialog.Combo.
- Date Field A date field displays the date specified in a global variable of type Dates.Date.
- Time Field A time field displays the time specified in a global variable of type Dates.Time.
- Color Field A color field displays a color. It can be linked to variables of type Ports.Color or Dialog.Color.
- UpDownField This is a field linked to an integer variable. The value can also be changed through arrow keys.
Additional controls can be implemented by third parties. An example is given in
ObxButtons
which is shown in Picture e.
Layout Mode and Mask Mode
Electronic forms are documents which can be manipulated in two special modes: in one mode, a form's layout is edited (layout mode). In layout mode, controls are passive: buttons can be selected, but not "pressed". No control can be made focus. In the other mode (mask mode), a form is used for data entry, usually in a dialog. In this mode, the form's layout cannot be changed anymore, but the controls become active, i.e. text can be entered in text fields, buttons can be pressed, etc. In mask mode, no control may be selected (see Picture d).
Picture d: A dialog (in mask mode) with several controls
Picture e A dialog (in layout mode) which contains three "ObxButtons" controls
In fact, it is also possible to enable both focus and selection, or to disable both, giving rise to an editor mode and a viewer mode, respectively. For forms processing, these additional modes are not relevant, however.
Auxiliary and Tool Windows
In typical electronic business forms, a button that is depressed causes an action on the form's contents, e.g. the data entered into the form is stored in a data base and cleared thereafter. However, there is an important special case of electronic forms where a button's action does not operate on the contents of its own form, but on another document' contents, in another window. The data that such a form contains act as parameters to its commands (i.e. its buttons). For example, a "Find & Replace" dialog may contain a text field labeled "find" and a button labeled "Find Next". The text field contains the string to be searched, and the button activates the search command. The search command then operates not on the dialog contents (the front window), but on the contents of the window beneath the dialog (the target window).
A dialog which acts as front but not simultaneously as target window is called a tool. A dialog which acts both as front and as target window is shown in an auxiliary window. Auxiliary windows can be recognized by the [ and ] brackets around their titles, e.g. "[ New Form ]". On some platforms, tool windows are denoted by angular brackets around their titles, e.g. "<<
Replace
Modal vs Non-Modal dialogs
Oberon/F currently supports non-modal forms only, i.e. dialogs or data entry masks which don't block the user from doing something else while the form is open, e.g. looking up information about the task currently performed. This means that windows with forms can be put away anytime, to suspend the task for a while and to later resume it, by bringing the window to the top again.
When working with non-modal dialogs, the procedure which opens the dialog cannot wait for results but rather has to return control to the system. As a consequence, state cannot be held in local variables, i.e. on the stack, but rather has to be extracted and managed explicitly in a separate stack-like data structure.
Dependencies between Dialogs and Programs
Ideally, forms design should be done by a professional in the graphics design and human interface fields, and program design should be done by a professional in the software engineering field. Thus these distinct tasks should be dependent on each other as little as possible. Yet the software engineer's final program must be able to work with the various forms that the human interface designer has developed, so some dependencies obviously exist.
These dependencies consist of three different parts: a program must manipulate data contained in a form, thus it must be able to get this data into its program variables; it must be able to put computed results residing in its program variables back into the form; and one of its procedures must be triggered when the user performs an interaction with a control.
Oberon/F handles these dependencies in a very convenient way: The basic idea is that the programmer should be relieved from mundane tasks like transferring data between program variables and controls as much as possible. Rather, a control should be able to monitor a program variable directly. Thus, when the user edits the data in a control, the change is immediately reflected in the corresponding program variable, without the need for intervention by the programmer. The other aspects of the dependencies between the controls and a module are described later. We will first concentrate on the generation of dialogs.
Form Generation
If a programmer only wants to describe the contents of a dialog (and not design it), he combines all variables to be presented in a form in one Oberon record, called an interactor. In this case, the record corresponds to the form, and the record fields to individual controls. A benefit of this convention is that Oberon/F can automatically generate a form out of a suitably defined record declaration. For example, an integer field is by default translated into a text entry field which only accepts integer numbers, a procedure-typed record field is translated into a push button, etc. The automatic generation of a form is particularly convenient if a user interface is only temporary, e.g. for testing purposes. In essence, it is a rapid prototyping aid.
Note that the controls in a dialog may correspond to variables in different modules and different records. The variables not necessarily need to be defined in an interactor, it could be unstructured global variables also. Furthermore, a dialog may contain non-control views which are not linked to global variables at all, e.g. bitmap views or text views (cf Picture d).
Instead of starting with the program, forms may also be defined first, and the suitable program written later. It is also possible to later change the linking between controls and program variables; to change the type of a variable's control (e.g. a text entry field for numbers may be replaced by a scroll bar); to edit the form's layout whenever desired; or to add graphical elements which do not appear as variables in the program because their use is only for decoration (e.g. a company logo in a form, see Picture d).
Remember that a form is stored in the standard Oberon/F compound document file format, and thus remains editable at any time. This is convenient e.g. when forms need to be translated from one (natural) language into another one, e.g. from English to German. In Oberon/F this is possible for someone who has no access to the program's source code, because no recompilation is necessary. This is in contrast to many other development systems which translate a form specification - even if generated using an interactive editor - into a program source text, which must be compiled and linked to the rest of the program. Such a source-code-generator approach can be considered obsolete today.
The consistency of an Oberon/F program with its forms is checked whenever a form is loaded. A control which is inconsistent with the variable to which it is linked (e.g. because the variable has been removed) can still be displayed, but is made inactive. This load-time check is possible because Oberon/F contains an advanced meta-programming system which makes all necessary type information available at run-time.
The following example demonstrates how a form can be generated automatically out of an interactor, and how a command may acquire its parameters through a dialog.
- A variable find is declared as record-typed global variable.
- For every procedure-typed record field there is a parameterless global procedure
- In the module's initialization part the procedure-typed fields of variable find are assigned
- The commands use the content of the fields as parameters
Picture f: "New Form" Dialog
You can try out this example in the following way: invoke New
Form... in the Dev menu, which opens the standard form generation dialog (see Picture f). In this dialog, type in "ObxForms0.find" in the link field, then click on the command button. As a result, a dialog is generated and opened (cf. Picture g). Open this dialog as an auxiliary window (use the command "Open As Aux Dialog" in the Dev menu), click on the various buttons, fill out the text fields, and look at the output in the log window. Also try to enter a name into the count field which is linked to the LONGINT variable ObxForms0.find.count.
Obviously, ObxForms0 does not actually implement a find & replace algorithm, but merely writes to the log. However, this is sufficient as a demonstration.
A newly generated form is always opened in layout mode, i.e. the form elements can be moved around, resized (cf. Picture h), and their properties may be modified using a special inspector tool. After editing, the form can be opened as a tool or as an auxiliary, where it can be used. To do that, execute Open
Dialog or Open As Aux Dialog in the Dev menu. In this way, you get a window in layout mode simultaneously with another one in mask mode, for the same form, as in the example below:
Picture h : Layout and Mask for the "Find & Replace" Dialog
After editing, the form can be saved as a Oberon/F document. Such documents can be opened with the command StdCmds.OpenAuxDialog or StdCmds.OpenToolDialog to open an auxiliary or a tool dialog. Both commands take two parameters, a file specification of an Oberon/F document and a window title. The following two examples open the "New Form" dialog (an auxiliary) and the "Find" dialog (a tool).
Such command sequences are usually put into the menu definition text.
Inspector
The properties of a control can be inspected and modified with the control property inspector. On Windows, this inspector can be opened with the Properties... command in submenu Object of menu Edit; on the Mac OS the command Component Info... in menu Edit opens the property inspector.
The link field displays the variable to which the control is linked. In case of a command button, the link field may also contain an Oberon/F command sequence to be executed when the button is pressed. The label field can be used to set the label of a command button, a radio button, a check box or a caption.
The level field is used for radio buttons. A radio button is active if the value of the integer variable it is linked to is equal to the level value. If a radio button is pressed, the value of the integer is set to the level value. Several radio buttons can be linked to the same integer variable, each with another level value. This guarantees that at most one of the radio buttons is active at the same time.
A command button can be set to be a default or a cancel button. Default buttons in a form can be activated with the return key, and a cancel button can be "pressed" with the escape key.
Picture i: Control Inspector with the Properties of the "Find" Command Button
Updating Controls from within Commands
While an interactive modification of a control is automatically reflected in the program variable, the opposite is not true: after assigning a new value to a variable to which several controls are linked, Oberon/F must be notified of the change. This is done with the Dialog.Update procedure. In order to be able to use this procedure, the interactor must be defined as a subtype of Dialog.Interactor, the type of the argument of Dialog.Update.
Our next example program is a variation of an example shown in the command tutorial (ObxText1) which computes the sum of the integer from 1 up to a given limit. In contrast to the older version, the new version allows to enter the upper limit of the sum to be calculated, using a form. The result is also displayed in the form. The loop in procedure Sum is used for demonstration purposes only. Obviously, the formula of Gauss could be used to compute the sum without any loop.
MODULE ObxForms1;
IMPORT Dialog, Out;
para*: RECORD (Dialog.Interactor)
limit*, sum*: LONGINT;
Sum*: PROCEDURE
END;
PROCEDURE Sum*;
VAR i, sum: LONGINT;
BEGIN
i := 1; sum := 0;
WHILE i <= para.limit DO
sum := sum + i;
i := i + 1
END;
para.sum := sum; Dialog.Update(para)
END Sum;
BEGIN
para.Sum := Sum
END ObxForms1.
The form can be generated and opened with the following command.
The user can enter a number in the limit control. This automatically updates the value of ObxForms1.para.limit. When the user clicks the Sum button (or presses the return key), the sum of 0 .. ObxForms1.para.limit is calculated and the ObxForms1.para.sum field is set to this sum and the dialog is updated.
Note that the result is wrong if the limit is larger than 65535 due to integer overflow. If we want to prevent this from happening, then we need to program a notifier.
Notifiers
Notifiers are called whenever the value of a control is changed. A notifier may be used to react as soon as the value of a control has changed. A dialog can so be kept consistent. In our summation example we could compute the sum whenever the limit field is changed. The Sum button would then no longer be necessary. Additionally, we can assert that the user only enters values which are valid.
MODULE ObxForms2;
IMPORT Dialog, Out;
para*: RECORD (Dialog.Interactor)
limit*, sum*: LONGINT;
END;
PROCEDURE NotifyLimit*(op, from, to: LONGINT);
VAR i, sum: LONGINT;
BEGIN
IF op = Dialog.changed THEN
IF para.limit > 65535THEN
Dialog.Beep; para.limit := from
ELSE
i := 1; sum := 0;
WHILE i <= para.limit DO
sum := sum + i;
i := i + 1
END;
para.sum := sum
END;
Dialog.Update(para)
END
END NotifyLimit;
END ObxForms2.
The Dialog now has to be generated with the command New Form ... in menu Dev and the value of the notify field of the limit field has to be set to ObxForms2.NotifyLimit. Then the dialog can be used. Try it!
Guards
A control guard command is a procedure with the signature PROCEDURE (VAR par: Dialog.Par). It can set the fields of the par parameter to suitable values, e.g. a guard can define whether a control is read-only, whether it is disabled or undefined. Guard commands are called to determine the current state of a control, in particular to find out whether the control is enabled. For example, the Create button in the New Form dialog is only enabled if the link field is not empty.
The guard commands are specified in the inspector dialog. Control guard commands are called after the user interactively changed the state of a control, or after a program calls the procedure Dialog.CheckGuards.
Our last version of the summation example defines a read-only guard which is used for the sum field. A read-only sum field is guaranteed to be consistent, i.e. the user can only change the limit field which automatically adjusts the sum field.
MODULE ObxForms3;
IMPORT Dialog, Out;
para*: RECORD (Dialog.Interactor)
limit*, sum*: LONGINT;
END;
PROCEDURE NotifyLimit* (op, from, to: LONGINT);
VAR i, sum: LONGINT;
BEGIN
IF op = Dialog.changed THEN
IF para.limit > 65535 THEN
Dialog.Beep; para.limit := from
ELSE
i := 1; sum := 0;
WHILE i <= para.limit DO
sum := sum + i;
i := i + 1
END;
para.sum := sum
END;
Dialog.Update(para)
END
END NotifyLimit;
PROCEDURE ReadOnlyGuard* (VAR par: Dialog.Par);
BEGIN
par.readOnly := TRUE
END ReadOnlyGuard;
END ObxForms3.
Try out the module with the following embedded dialog (an embedded form view which contains two fields):
You might also use the following embedded text fields. Both fields are linked to the interactor ObxForms3.para, and the notifier of the left field is set to ObxForms3.NotifyLimit. If you change the value in the left field, the right field is automatically updated. If you only update the left field, the sentence is consistent.
The sum of integers from 1 to
is
Working with Commands
In Oberon, an exported procedure to be called by the user is called a command. In any Oberon environment, the user should be able to call a command, given the command's name and the name of the module that contains the command. A command is the atomic action that a user can execute, which means that commands may only be executed sequentially, not concurrently.
A command always performs two tasks: first, it assembles the parameters that it needs. These parameters can be any part of the whole Oberon environment's global state. If a command uses global state about which the user does not know, the command becomes difficult to use, since its effect becomes unpredictable from a user's point of view. Such hidden modes should be avoided in good user interface designs, thus commands should only depend on state which is somehow visible to the user, e.g. the focus, its selection, its caret, etc.
After the command's parameters have been gathered, an action is invoked with these parameters, e.g. closing a window, deleting selected text, or storing a form's contents into a database.
For the user, there may be several ways to call a command. One way might be to press a button in a form, another way may be the activation of a text stretch which has the form "module.procedure". However, the most typical way is to select a menu item.
After the core of Oberon/F has been started up, it tries to find a text document with file name Menus. This text contains the initial menu configuration. An example may look as follows:
menuname, typename, itemname, shortcut, command, and guard are strings delimited by double quotes.
typename must contain the name of a record type in the form "module.record". Commands and guards must contain Oberon command sequences.
Menu definitions which specify a typename define context-sensitive menus. Such menus are only available if the focus view supports this context, i.e. returns this typename. A view may specify which context it supports by setting the type field of the Controllers.PollOpsMsg. For more information read the section Controller Messages in the view tutorial.
A menu consists of several items. An item is either a single menu entry, or a separator. Separators are used to visually group menu entries in a menu. A menu entry has a visible representation (the item's name, as a string), possibly a keyboard shortcut, a command, and a guard. When the menu entry is selected, the command described by the command string is executed.
By editing the Menus text, menu items or whole menus can be deleted or added.
Mac OS:
The standard menus like File, Edit, Attributes, and Windows cannot be reconfigured, and thus do not appear in the configuration text.
Note that several menus of the standard configuration have a type name after the keyword MENU, written in parentheses. If no such type name is given, the menu is always available. If a type name is given, the corresponding menu is context-sensitive, i.e. only available if the focus is of the given type. The text menu, for example, only appears when a text view is focused.
Menus can be changed at run-time: create the menu text with the Menus command in the Info menu. Then add e.g. the following item to the Dev menu:
Menus command in the Info menu to update the menus. Now you can execute the new command by selecting the appropriate menu entry. It attempts to paste a clock into the front window's document.
If you want to make the new menu configuration permanent, save the menu text in the Rsrc subdirectory, which resides in the System subdirectory of Oberon/F.
Working with Files
In Oberon/F, files play a less central role than in most programming environments, because the programmer only works with files indirectly. You stand a good chance that you'll never use the file interface directly. For this reason, we don't recommend that you concentrate on files when learning about Oberon/F, you should rather look at Oberon/F views (see the view tutorial) as the pivotal abstraction of the component framework. The only reasons for using files directly are the handling of legacy files produced with other software, and the implementation of simple file-based database systems.
However, since files are important traditional abstractions in computer science, and form the basis of the persistent storage mechanism of Oberon/F, a short introduction is given anyway.
Normally, data is written to a file ("externalized") and read from a file ("internalized") via so-called mapper objects, which perform the mapping of byte streams to higher-level data structures and vice versa. These mappers are provided by the framework where they are needed. Module Stores provides two such mappers, a Stores.Reader for internalization and a Stores.Writer for externalization. File mappers internally contain objects which connect them to files. These connecting objects are called file riders. There are two flavors of file riders, one for internalization and one for externalization.
Picture j: File with three Riders
We'll first show how files can be accessed through direct use of riders, and then how they can be used via file mappers. The first of our examples demonstrates how an existing file is looked up, how its contents are copied to a new file, and how the new file is permanently registered in the file directory:
MODULE ObxFiles0;
IMPORT Files;
PROCEDURE Do*;
VAR s: Files.Locator; old, new: Files.File; r: Files.Reader; w: Files.Writer;
ch: CHAR; res: LONGINT;
BEGIN
s := Files.dir.This("Obx"); (* get locator for Obx subdirectory *)
s := s.This("Samples"); (* get locator for Samples subdirectory *)
old := Files.dir.Old(s, "Test0", Files.shared); (* look up file "Test0" *)
ASSERT(old # NIL, 20); (* abort program if file not found *)
new := Files.dir.New(s); (* create a new file at same location*)
r := old.NewReader(NIL); r.SetPos(0); (* create a rider for internalization *)
w := new.NewWriter(NIL); w.SetPos(0); (* create a rider for externalization *)
r.ReadByte(ch);
WHILE ~r.eof DO (* stop when end of file is reached *)
w.WriteByte(ch);
r.ReadByte(ch)
END;
new.Register("Test1", old.type, res) (* register copy as "Test1" *)
END Do;
END ObxFiles0.
In this program, a file is looked up in three steps. In the first step, the file directory object Files.dir delivers a locator for subdirectory Obx. All other file directory operations take such a locator as parameter. In the second step, a locator for directory Samples in Obx is created, i.e. of directory Obx/Samples. In the third step, the directory delivers a file object, provided a file with the given name exists. Files may be opened in shared mode or in exclusive mode. Usually, shared mode is used, which means that several invocations of Files.dir.Old for the same file yield the same file object; no one may alter the contents of this file.
If the file's contents should be altered, a new file is generated instead. After the new file has been written, it replaces the old one. This replacement process is called registration. Registration is atomic, i.e. it either finishes successfully or it is aborted completely, but it will never destroy the contents of the old file during an abort. In the above example, the file is saved at the same location and with the same file type, but under another name.
ObxFiles0 copies the contents of an old file to a newly created file. For that purpose, the old file produces a Files.Reader, and the new file produces a Files.Writer. These are the file riders mentioned earlier. They provide procedures to read, respectively to write, bytes, in the form of one-byte characters. Before they are used, their current positions must be set up (using their SetPos procedures). When a file reader attempts to read beyond the end of the file, it sets its eof flag to indicate this situation.
ObxFiles0 shows another facility of the language Oberon: the ASSERT statement. An ASSERT statement checks a Boolean condition. If this condition is TRUE, it does nothing. If the condition is FALSE however, it aborts the program and gives an error message. The second parameter of an ASSERT, which must be an integer constant in the range 0..127, is displayed as part of the error message.
Oberon/F makes extensive use of ASSERT statements, in particular to make sure that its procedures are called with legal parameters. For example, the procedure Files.dir.Old asserts that its locator parameter is not NIL, otherwise error 20 occurs.
Apart from helping to detect errors early, assertions also are valuable as documentation of a program's properties. They are particularly helpful during design iterations and maintenance of a program.
Assertions which test for legal input state of a procedure are called precondition assertions. An assertion checking the outcome of a procedure is called a postcondition assertion. Assertions in the middle of a procedure, to check against errors in it, are called invariant assertions. Precondition assertions are the most important of these assertion types in Oberon/F. As a convention, all three types have their own assertion number ranges, as given below. The first range (0..19) is free for your use, typically as breakpoints using the HALT statement.
Free
0 ..
Preconditions
20 ..
Postconditions
60 ..
Invariants 100 .. 120
Reserved 121 .. 125
Not Yet Implemented 126
Interface Procedure Called 127
When an assertion error (or halt) occurs, a window is opened with the so-called debug trap text. Among other things, it displays the assertion number and the name of the procedure where this assertion was violated. You can use this information to look up what was wrong in the on-line reference information.
The following program is another example of how file riders and the end-of-file flag can be used. This example module could be used as a library module, i.e. a module which provides a generally useful service to other modules, but which is no complete application of its own:
WHILE ~a.eof & ~b.eof DO (* stop when one or both files have been read *)
IF inA < inB THEN (* choose smaller input *)
c.WriteByte(inA); a.ReadByte(inA)
ELSE
c.WriteByte(inB); b.ReadByte(inB)
END
END;
WHILE ~a.eof DO c.WriteByte(inA); a.ReadByte(inA) END;
WHILE ~b.eof DO c.WriteByte(inB); b.ReadByte(inB) END
END Merge;
END ObxFiles1.
The next example illustrates how data can be written to a file, and how it can be retrieved from the file again. As with all typical applications, mappers are used instead of riders. A file mapper (either a reader or a writer) provides input/output routines for the basic Oberon data types and for character arrays (strings):
MODULE ObxFiles2;
IMPORT Files, Stores;
PROCEDURE Write* (a: INTEGER; s: ARRAY OF CHAR; b: BOOLEAN);
VAR loc: Files.Locator; f: Files.File; w: Stores.Writer; res: LONGINT;
BEGIN
loc := Files.dir.This("");
f := Files.dir.New(loc);
w.ConnectTo(f); (* set up mapper w on file f *)
w.WriteString(s);
w.WriteInt(a);
w.WriteBool(b);
f.Register("Test2", "", res) (* should use a suitable file type here *)
END Write;
PROCEDURE Read* (VAR a: INTEGER; VAR s: ARRAY OF CHAR; VAR b: BOOLEAN);
VAR loc: Files.Locator; f: Files.File; r: Stores.Reader;
BEGIN
loc := Files.dir.This("");
f := Files.dir.Old(loc, "Test2", Files.shared); ASSERT(f # NIL, 20);
r.ConnectTo(f); (* set up mapper on file f *)
r.ReadString(s);
r.ReadInt(a);
r.ReadBool(b) (* a shareable file need not be closed, *)
END Read;
END ObxFiles2.
In contrast to the earlier examples, the next program shows how a file is opened exclusively and updated locally, i.e. no new file is generated and registered, but an old one is modified in place:
MODULE ObxFiles3;
IMPORT Files, Stores;
PROCEDURE Update*;
VAR loc: Files.Locator; f: Files.File; w: Stores.Writer;
BEGIN
loc := Files.dir.This("Obx");
loc := loc.This("Samples");
f := Files.dir.Old(loc, "Test0", Files.exclusive); (* access file Obx/Samples/Test0 *)
IF f # NIL THEN (* file is found and not yet open *)
w.ConnectTo(f);
w.SetPos(4);
w.WriteString("abcde"); (* overwrite five characters *)
f.Close (* exclusively opened files should be closed *)
END
END Update;
END ObxFiles3.
Note that if the file were opened in shared mode, the w.ConnectTo(f) call would have been aborted with a run-time error: a writer cannot be connected to a file opened as shareable, because this implies a read-only permission.
(.txt)